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Foreword 



This Technical Specification has been produced by the 3' Generation Partnership Project (3GPP). 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 
where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 11 of a multi-part TS covering the 3' Generation Partnership Project: Technical 
Specification Group Core Network; Open Service Access (OSA); Application Programming Interface (API), as 
identified below. The API specification (3GPP TS 29.198) is structured in the following Parts: 



Parti 
Part 2 
Part 3 
Part 4 



Part 5: 
Part 6: 
Part 7: 
Part 8: 
Part 9: 
Part 10: 
Part 11 
Part 12 
Part 13 
Part 14 
Part 15 



"Overview"; 

"Common Data Definitions"; 

"Framework"; 

"Call Control"; 

Sub-part 1: "Call Control Common Definitions"; 

Sub-part 2: "Generic Call Control SCF"; 

Sub-part 3: "Multi-Party Call Control SCF"; 

Sub-part 4: "Multi-Media Call Control SCF"; 

Sub-part 5: "Conference Call Control SCF"; 

"User Interaction SCF"; 

"Mobility SCF"; 

"Terminal Capabihties SCF"; 

"Data Session Control SCF"; 

"Generic Messaging SCF"; 

"Connectivity Manager SCF"; 

"Account Management SCF"; 

"Charging SCF". 

"Policy Management SCF"; 

"Presence and Availability Management SCF"; 

"Multi Media Messaging SCF"; 



(not part of 3GPP Release 6) 



(not part of 3GPP Release 6) 
(not part of 3GPP Release 6) 



(new in Release 6) 



The Mapping specification of the OSA APIs and network protocols (3GPP TR 29.998) is also structured as above. 
A mapping to network protocols is however not applicable for all Parts, but the numbering of Parts is kept. 
Also in case a Part is not supported in a Release, the numbering of the parts is maintained. 
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Table: Overview of the OSA APIs & Protocol Mappings 29.198 & 29.998-family 



OSA API specifications 29.198-family 


OSA API Mapping - 29.998-family 


29.198-01 


Overview 


29.998-01 


Overview 


29.198-02 


Common Data Definitions 


29.998-02 


Not Applicable 


29.198-03 


Framework 


29.998-03 


Not Applicable 


Call 
Control 
(CC) 
SCF 


29.198- 
04-1 

Common 
CC data 
definitions 


29.198- 
04-2 
Generic 
CCSCF 


29.198- 
04-3 
Multi- 
Party CC 
SCF 


29.198- 
04-4 
Multi- 
media CC 
SCF 


29.998-04-1 


Generic Call Control - CAP mapping 


29.998-04-2 


Generic Call Control - INAP mapping 


29.998-04-3 


Generic Call Control - Megaco mapping 


29.998-04-4 


Multiparty Call Control - ISC mapping 


29.198-05 


User Interaction SCF 


29.998-05-1 


User Interaction - CAP mapping 


29.998-05-2 


User Interaction - INAP mapping 


29.998-05-3 


User Interaction - Megaco mapping 


29.998-05-4 


User Interaction - SMS mapping 


29.198-06 


Mobility SCF 


29.998-06 


User Status and User Location - MAP mapping 


29.198-07 


Terminal Capabilities SCF 


29.998-07 


Not Applicable 


29.198-08 


Data Session Control SCF 


29.998-08 


Data Session Control - CAP mapping 


29.198-09 


Generic Messaging SCF 


29.998-09 


Not Applicable 


29.198-10 


Connectivity Manager SCF 


29.998-10 


Not Applicable 


29.198-11 


Account Management SCF 


29.998-11 


Not Applicable 


29.198-12 


Charging SCF 


29.998-12 


Not Applicable 


29.198-13 


Policy Management SCF 


29.998-13 


Not Applicable 


29.198-14 


Presence & Availability Management SCF 


29.998-14 


Not Applicable 


29.198-15 


Multi-media Messaging SCF 


29.998-15 


Not Applicable 
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Scope 



The present document is Part 1 1 of the Stage 3 specification for an Application Programming Interface (API) for Open 
Service Access (OS A). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardised interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Account Management Service Capability Feature (SCF) aspects of the interface. All 
aspects of the Account Management SCF are defined here, these being: 

Sequence Diagrams 

Class Diagrams 

Interface specification plus detailed method descriptions 

State Transition diagrams 

Data definitions 

IDL Description of the interfaces 

WSDL Description of the interfaces 

The process by which this task is accomplished is through the use of object modelling techniques described by the 
Unified ModelUng Language (UML). 

This specification has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and the Parlay Group, in co- 
operation with a number of JAIN^"^ Community member companies. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TS 29.198-1 "Open Service Access; Application Programming Interface; Part 1: Overview". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] ISO 4217: "Codes for the representation of currencies and funds". 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in TS 29.198-1 [1] apply. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in TS 29.198-1 [1] apply. 

4 Account IVIanagement SCF 

The following clauses describe each aspect of the Account Management Service Capability Feature (SCF). 

The order is as follows: 

The Sequence diagrams give the reader a practical idea of how each of the SCFs is implemented. 

The Class relationships clause shows how each of the interfaces applicable to the SCF, relate to one another 

The Interface specification clause describes in detail each of the interfaces shown within the Class diagram part. 

The State Transition Diagrams (STD) show the progression of internal processes either in the application, or 
Gateway. 

The Data definitions section shows a detailed expansion of each of the data types associated with the methods 
within the classes. Note that some data types are used in other methods and classes and are therefore defined 
within the Common Data types part of this specification. 

4.1 General requirements on support of methods 

An implementation of this API which supports or implements a method described in the present document, shall 
support or implement the functionality described for that method, for at least one valid set of values for the parameters 
of that method. 

Where a method is not supported by an implementation of a Service interface, the exception 
P_METHOD_NOT_SUPPORTED shall be returned to any call of that method. 

Where a method is not supported by an implementation of an Application interface, a call to that method shall be 
possible, and no exception shall be returned. 



5 Sequence Diagrams 

5.1 Standard Voucher Handling 
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bAppAccountManaqer 



^^ 



IpAccountManaqer 



The application queries tine 
vouclier amount 



1 : queryVoucherReq( ) 



2: queryVouclierRes( ) 



The application updates the balance 
of the account 



3: updateBalanceReq( ) 



4: updateBalanceRes( ) 



5: destroyVoucherReq( ) 



6: destroy VoucherRes( ) 



1: This message is used to get a voucher for an amount. 

2: This message used to return the amount requested. 

3: This message is used to update the balance of the account. 

4: This message is used to return the confirmation of the update. 
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5: This message is used to remove the voucher. 

6: This message is used to confirm that the voucher is removed. 

5.2 Standard Transaction History Retrieval 



IpAppAccountManaqer IpAccountManaqer 

1 : retrieve TransactionHistoryReq( ) 



2: retrieve TransactionHistoryRes( ) 



1 : This message is used by the application to retrieve a transaction history for a certain subscriber's account. 

2; This method passes the result of the transaction history retrieval request for a specific user to its callback object. 



5.3 Standard Query Handling 
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IpAppAccountManaqer 



: IpAccountManaqer 



Application is requesting to query 
the balance 



1:queryBalanceReq( 



2:queryBalanceRes( 



Application is requesting to query the 
balance, butthere is at least one error in the 
parameters that is detected by the 
IpAccountManager service. 

3: queryBalanceReq( ) 



Application is requesting to query the 
balance, but a network error occurs 



4: queryBalanceReq( ) 



5:queryBalanceErr( ) 



1 : This message is used to query the balance of the account of one or several users. 

2: This message passes the result of the balance query for one or several users to its callback object. 

3: This scenario shows the case where at least one error in the parameters of the message is detected by the 
IpAccountManager object. An exception will be thrown. 

4: This scenario shows the case where a network error occurs. 

5: This message passes the error of the balance query. No exception is thrown. 
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5.4 Standard Notification handling 



IpAppAccountManaqer 



<- 



1:createNotification( 



2:reportNotification( 



IpAccountManager 



3:getNotification( 



4:changeNotification( 



<- 



5:reportNotification( 



6: destroyNotification( 



1: This message is used by the application to request notifications from the IpAccountManager service on certain 
criteria for one or several users. 

2: This message is used by the IpAccountManager service to report a charging event that meets the criteria set in the 
createNotification message. 

3: The application can request the current criteria set in the IpAccountManager service by invoking the getNotification 
method. 

4: This message is used by the application to change the criteria initially created by createNotification, and previously 
obtained by getNotification. 

5: This message is used by the IpAccountManager service to report a charging event that meets the new criteria. 
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6: This method is used by the application to disable the charging notifications. 



5.5 Network Controlled Notifications 

The following sequence diagram shows how an application can receive notifications that have not been created by the 
application, but are provisioned fi'om within the network. 



AppLoqic : IpAppAccountManaqer : IpAccountManaqer 

I 
1 

i 1 : New() 



2: enableNot|fications( ) 



^ 



4: 'forward event' 



-<- 



3: reportNotification( ) 



6: 'forward event' 



-<- 



5: reportNotification( ) 



7: disableNotiifications( ) 



^ 



1: The application is started. The application creates a new IpAppAccountManager to handle callbacks. 

2: The enableNotifications method is invoked on the IpAccountManager interface to indicate that the application is 
ready to receive notifications that are created in the network. For illustrative purposes we assume notifications of type 
"B" are created in the network. 

3: When a network created trigger occurs the application is notified on the callback interface. 

4: The event is forwarded to the application. 

5: When a network created trigger occurs the application is notified on the callback interface. 

6: The event is forwarded to the application. 
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7: When the application does not want to receive notifications created in the network anymore, it invokes 
disableNotifications on the IpMultiPartyCallConrolManager interface. From now on the gateway will not send any 
notifications to the application that are created in the network. The application will still receive notifications that it has 
created himself until the application removes them. 



Class Diagrams 
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<<lnterface» 
Iplnterface 

(from csapi) 



<<lnterface>> 
IpAppAccount Manager 

reportNotificationO 
queryBalanceResQ 
queryBalanceErrQ 
retrieveTransactionHistoryResQ 
retrieveTransactionHistoryErrQ 
«new» queryBalanceExpiryDateResQ 
<<new» queryBalanceExpiryDateErrQ 
<<new» updateBalanceResQ 
«new» updateBalanceErrQ 
<<new» createVoucherResQ 
<<new» createVoucherErrQ 
<<new» destroy VoucherResQ 
<<new» destroyVoucherErrQ 
<<new» queryVoucherResQ 
<<new» queryVoucherErrQ 
<<new» query UserVouchersResQ 
<<new» queryUserVouchersErrQ 



<<uses» 



«lnterface>> 
IpAccountManager 



createNotificationQ 

destroyNotificationO 

queryBalanceReqO 

changeNotificationQ 

getNotificationQ 

retrieveTransactionHistoryReqO 

enableNotificationsQ 

disableNotificationsO 

<<new» queryBalanceExpiryDateReqO 

<<new» updateBalanceReqQ 

<<new» createVoucherReqQ 

<<new» destroyVoucherReqO 

<<new» queryVoucherReqO 

<<new» queryUserVouchersReqO 
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Figure: Application Interfaces 



IpSerMce 



setCallbackO 
setCallbackWithSessionlDQ 



«lnterface» 
IpAccountManager 

(from am) 



HcreateNotificationO 

^destroyNotificationO 

^queryBalanceReqO 

l^changeNotificationO 

^getNotificationQ 

^retrieveTransactionHistoryReqO 

^enableNotificationsO 

^disableNotificationsO 

^«new» queryBalanceExpiryDateReqO 

^«new» updateBalanceReqQ 

H«new» createVoucherReqO 

P«new» destroyVoucherReqO 

^«new» queryVoucherReqO 

^«new» queryUserVouchersReqO 



Figure: Service Interfaces 



7 The Service Interface Specifications 

7.1 Interface Specification Format 

This clause defines the interfaces, methods and parameters that form a part of the API specification. The Unified 
Modelling Language (UML) is used to specify the interface classes. The general format of an interface specification is 
described below. 
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7.1.1 Interface Class 

This shows a UML interface class description of the methods supported by that interface, and the relevant parameters 
and types. The Service and Framework interfaces for enterprise-based client applications are denoted by classes with 
name Ip<name>. The callback interfaces to the applications are denoted by classes with name IpApp<name>. For 
the interfaces between a Service and the Framework, the Service interfaces are typically denoted by classes with name 
IpSvc<name>, while the Framework interfaces are denoted by classes with name IpFw<name>. 

7.1 .2 Method descriptions 

Each method (API method 'call') is described. Both synchronous and asynchronous methods are used in the API. 
Asynchronous methods are identified by a 'Req' suffix for a method request, and, if applicable, are served by 
asynchronous methods identified by either a 'Res' or 'Err' suffix for method results and errors, respectively. To handle 
responses and reports, the application or service developer must implement the relevant IpApp<name> or 
IpSvc<name> interfaces to provide the callback mechanism. 

7.1.3 Parameter descriptions 

Each method parameter and its possible values are described. Parameters described as 'in' represent those that must have 
a value when the method is called. Those described as 'out' are those that contain the return result of the method when 
the method returns. 

7.1.4 State Model 

If relevant, a state model is shown to illustrate the states of the objects that implement the described interface. 

7.2 Base Interface 

7.2.1 Interface Class Iplnterface 

All application, framework and service interfaces inherit from the following interface. This API Base Interface does not 
provide any additional methods. 



«lnterface» 
Iplnterface 



7.3 Service Interfaces 
7.3.1 Overview 

The Service Interfaces provide the interfaces into the capabilities of the underlying network - such as call control, user 
interaction, messaging, mobility and connectivity management. 

The interfaces that are implemented by the services are denoted as 'Service Interface'. The corresponding interfaces that 
must be implemented by the application (e.g. for API callbacks) are denoted as 'Application Interface'. 
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7.4 



Generic Service Interface 



7.4.1 Interface Class IpService 

Inherits from: Iplnterface 

All service interfaces inherit from the following interface. 



«lnterface» 
IpService 



setCallback (applnterface : in IplnterfaceRef) : void 

setCallbackWitinSessionlD (applnterface : in IplnterfaceRef, sessionID : in TpSessionID) : void 



7.4.1.1 



Method setCallbackO 



This method specifies the reference address of the callback interface that a service uses to invoke methods on the 
application. It is not allowed to invoke this method on an interface that uses SessionlDs. Multiple invocations of this 
method on an interface shall result in multiple callback references being specified. The SCS shall use the most recent 
callback interface provided by the application using this method. In the event that a callback reference fails or is no 
longer available, the next most recent callback reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

Raises 

TpCommonExceptions , P_INVALID_INTERFACE_TYPE 



7.4.1.2 



Method setCallbackWithSessionlDO 



This method specifies the reference address of the application's callback interface that a service uses for interactions 
associated with a specific session ID: e.g. a specific call, or call leg. It is not allowed to invoke this method on an 
interface that does not use SessionlDs. Multiple invocations of this method on an interface shall result in multiple 
callback references being specified. The SCS shall use the most recent callback interface provided by the application 
using this method. In the event that a callback reference fails or is no longer available, the next most recent callback 
reference available shall be used. 

Parameters 

applnterface : in IplnterfaceRef 

Specifies a reference to the application interface, which is used for callbacks. 

sessionID : in TpSessionID 

Specifies the session for which the service can invoke the appUcation's callback interface. 
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Raises 

TpCommonExceptions, P_INVALID_SESSION_ID, P_INVALID_INTERFACE_TYPE 



8 Account Management Interface Classes 

8.1 Interface Class IpAccountManager 

Inherits from: IpService. 

The account manager interface provides methods for managing accounts. Applications can use this interface to enable 
or disable charging-related event notifications and to manage account balances. Vouchers allow indirect references to 
amounts that can be applied to the account. 

This interface shall be implemented by an Account Management SCF. The queryBalanceReqO method, or the 
retrieveTransactionHistoryReqO method, or both the createNotification() and destroyNotification methods, or both the 
enableNotifications and disableNotifications methods shall be implemented as a minimum requirement. 



«lnterface» 
IpAccountManager 



createNotification (appAccountManager : in IpAppAccountManagerRef, chargingEventCriteria : in 
TpCinargingEventCriteria) : TpAssignmentID 

destroyNotification (assignmentid : in TpAssignmentID) : void 

queryBalanceReq (users : in TpAddressSet) : TpAssignmentID 

changeNotification (assignmentID : in TpAssignmentID, eventCriteria : in TpCinargingEventCriteria) : void 

getNotification () : TpChargingEventCriteriaResultSet 

retrieveTransactionHistoryReq (user : in TpAddress, transactionlnterval : in TpTimelnterval) : 
TpAssignmentID 

enableNotifications (appAccountManager : in IpAppAccountManagerRef) : TpAssignmentID 

disableNotifications () : void 

«new» queryBalanceExpiryDateReq (users : in TpAddressSet) : TpAssignmentID 

«new» updateBalanceReq (user : in TpAddress, debit : in TpBoolean, amount : in TpBalancelnfo, period 
in Tplnt32) : TpAssignmentID 

«new» createVoucherReq (user : in TpAddress, amount : in TpBalancelnfo) : TpAssignmentID 

«new» destroyVoucherReq (voucherld : in TpAssignmentID) : TpAssignmentID 

«new» queryVoucherReq (voucherld : in TpAssignmentID) : TpAssignmentID 

«new» queryUserVouchersReq (user : in TpAddress) : TpAssignmentID 



8.1.1 Method createNotificationO 

This method is used by the application to enable charging event notifications to be sent to the application. 

If the same application invokes this method multiple times with exactly the same criteria but with different callback 
references, then these shall be treated as additional callback references. Each such notification request shall share the 
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same assignmentlD. The SCS shall use the most recent callback interface provided by the application using this method. 
In the event that a callback reference fails or is no longer available, the next most recent callback reference available 
shall be used. 

In case the createNotification contains no callback, at the moment the application needs to be informed the gateway will 
use as callback the callback that has been registered by setCallbackQ. 

Returns assignmentid : Specifies the ID assigned by the account management object for this newly enabled event 
notification. 

Parameters 

appAccountManager : in IpAppAccountManagerRef 

If this parameter is set (i.e. not NULL) it specifies a reference to the application interface, which is used for callbacks. If 
set to NULL, the application interface defaults to the interface specified via the setCallback() method. 

chargingEventCriteria : in TpChargingEventCriteria 

Specifies the event specific criteria used by the application to define the charging event required. Individual addresses 
or address ranges may be specified for subscriber accounts. Example of events are "charging" and "recharging". 

Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions, P_INVALID_ADDRESS, P_INVALID_CRITERIA, 
P_INVALID_EVENT_TYPE , P_UNICNOWN_SUBSCRIBER 



8.1 .2 Method destroyNotificationQ 



This method is used by the application to disable charging notifications. This method only applies to notifications 
created with createNotification(). 

Parameters 

assignmentid : in TpAss ignment ID 

Specifies the assignment ID that was given by the account management object when the application enabled the 
charging notification. 

Raises 

TpCommonExceptions , P_INVALID_ASSIGNMENT_ID 



8.1 .3 Method queryBalanceReqO 



This method is used by the application to query the balance of an account for one or several users. A 
queryBalanceResO will be sent for all valid users, and a queryBalanceErr() will be sent for all invalid users or other 
errors. 

Returns queryld : Specifies the ID of the balance query request. 
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Parameters 

users : in TpAddressSet 

Specifies the user(s) for which the balance is queried. 

Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions , P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION 



8.1 .4 Method changeNotificationQ 

This method is used by the appHcation to change the event criteria introduced with createNotification. Any stored 
criteria associated with the specified assignmentID will be replaced with the specified criteria. 

Parameters 

assignmentID : in TpAssignmentID 

Specifies the ID assigned by the manager interface for the event notification. 

eventCriteria : in TpChargingEventCriteria 

Specifies the new set of event criteria used by the application to define the event required. Only events that meet these 
criteria are reported. 

Raises 

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID, P_INVALID_CRITERIA, 
P_INVALID_EVENT_TYPE, P_UNKNOWN_SUBSCRIBER, P_INVALID_ADDRESS 



8.1 .5 Method getNotificationQ 

This method is used by the application to query the event criteria set with createNotification or changeNotification. 

Returns eventCriteria : Specifies the event criteria used by the application to define the event required. Only events that 
meet these criteria are reported. 

Parameters 

No Parameters were identified for this method 

Returns 
TpChargingEventCriteriaResultSet 

Raises 
TpCommonExceptions 
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8.1.6 Method retrieveTransactionHistoryReqQ 

This asynchronous method is used by the application to retrieve a transaction history of a subscriber's account. The 
history is a set of Detailed Records. 

Returns retrievallD : Specifies the retrieval ID of the transaction history retrieval request. 

Parameters 

user : in TpAddress 

Specifies the subscriber for whose account the transaction history is to be retrieved. 

transactionlnterval : in TpTimelnterval 

Specifies the time interval for which the application history is to be retrieved. 

Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions , P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION, 
P INVALID TIME AND DATE FORMAT 



8.1.7 Method enableNotificationsQ 

This method is used to indicate that the application is able to receive which are provisioned from within the network 
(i.e. these notifications are NOT set using createNotification() but via, for instance, a network management system). If 
notifications provisioned for this application are created or changed, the application is unaware of this until the 
notification is reported. 

If the same application invokes this method multiple times with different IpAppAccountManager references, then these 
shall be treated as additional callback references. Each such notification request shall share the same assignmentlD. The 
SCS shall use the most recent callback interface provided by the application using this method. In the event that a 
callback reference fails or is no longer available, the next most recent callback reference available shall be used. 

When this method is used, it is still possible to use createNotification() for service provider provisioned notifications on 
the same interface as long as the criteria in the network and provided by createNotificationQ do not overlap. However, it 
is NOT recommended to use both mechanisms on the same service manager. 

The methods changeNotification(), getNotification(), and destroyNotification() do not apply to notifications provisioned 
in the network and enabled using enableNotifications(). These only apply to notifications created using 
createNotificationO . 

Returns assignmentlD: Specifies the ID assigned by the manager interface for this operation. This ID is contained in 
any reportNotification() that relates to notifications provisioned from within the network Repeated calls to 
enableNotificationsO return the same assignment ID. 

Parameters 

appAccountManager : in IpAppAccountManagerRef 

If this parameter is set (i.e. not NULL) it specifies a reference to the application interface, which is used for callbacks. If 
set to NULL, the application interface defaults to the interface specified via the setCallback() method. 
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Returns 

TpAs s ignment ID 

Raises 
TpCommonExceptions 

8.1 .8 Method disableNotifications() 

This method is used to indicate that the application is not able to receive notifications for which the provisioning has 
been done from within the network, (i.e. these notifications that are NOT set using createNotification() but via, for 
instance, a network management system). After this method is called, no such notifications are reported anymore. 

Parameters 

No Parameters were identified for this method 

Raises 
TpCommonExceptions 

8.1 .9 Method «new» queryBalanceExpiryDateReqO 

This method is used by the application to query the expiration date of the account. The returned date is the date the 
current balance will expire. Nil is returned if the balance does not expire. A queryBalanceExpiryDateRes() will be sent 
for all valid users, and a queryBalanceExpiryDateErr() will be sent for all invalid users or other errors. 

Returns queryld: Specifies the ID of the balance expiry date query request. 

Parameters 

users : in TpAddressSet 

Specifies the user(s) for which the balance expiry date is queried. 

Returns 

TpAss ignment ID 

Raises 

TpCommonExceptions , P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION 

8.1.10 Method «new» updateBalanceReqO 

This method is used by the application to update the balance of the account. 
Returns requestid: Specifies the ID of the update balance request. 

Parameters 

user : in TpAddress 

Specifies the user for which the balance update will be done. 
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debit : in TpBoolean 

Specifies that the amount will be subtracted from the balance if the debit parameter is true, or that the amount will be 
added to the account if the debit parameter is false. 

amount : in TpBalancelnfo 

Specifies the amount that will be added or subtracted to the user's account. The charge is specified as a currency 
amount. 

period : in Tplnt32 

Specifies the period at which the balance will expire. The balance is requested to expire in a number of days indicated 
by the period parameter. The operator's policy may overrule this parameter. If the period parameter is 0, the operator's 
policy on the balance expiration is always in effect. 

Returns 

TpAs s ignmen 1 1 D 

Raises 

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION 



8.1 .11 Method «new» create VoucherReqO 

This method is used by the application to create a voucher for an amount. 
Returns requestid: Specifies the ID of the voucher create request. 

Parameters 

user : in TpAddress 

Specifies the user for which the voucher create will be done. 

amount : in TpBalancelnfo 

Specifies the amount of the voucher. The charge is specified as a currency amount. 

Returns 
TpAssignmentID 

Raises 

TpCommonExceptions , P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION 

8.1.12 Method «new» destroyVoucherReqO 

This method is used by the application to destroy a voucher for an amount. 
Returns requestid: Specifies the ID of the destroy voucher request. 

Parameters 

voucherld : in TpAssignmentID 

Specifies the voucher to be destroyed. 
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Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions , P_UNAUTHORIZED_APPLICATION, P_INVALID_ASSIGNMENT_ID 

8.1.13 Method «new» queryVoucherReqO 

This method is used by the application to get the voucher information. 
Returns queryld: Specifies the identifier for this request. 

Parameters 

voucherld : in TpAss ignment ID 

Specifies the voucher to be queried. 

Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions , P_UNAUTHORIZED_APPLICATION, P_INVALID_ASSIGNMENT_ID 

8.1.14 Method «new» queryUserVouchersReqQ 

This method is used by the apphcation to get the vouchers for a user. 
Returns queryld: Specifies the ID for the get vouchers request. 

Parameters 

user : in TpAddress 

Specifies the user for which the vouchers will be returned. 

Returns 

TpAs s ignment ID 

Raises 

TpCommonExceptions , P_UNKNOWN_SUBSCRIBER, P_UNAUTHORIZED_APPLICATION, 
P INVALID ASSIGNMENT ID 



8.2 Interface Class I pAppAccount Manager 

Inherits from: Iplnterface. 

The account manager application interface is implemented by the client application developer and is used to handle 
charging event notifications and query balance responses. 
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«lnterface» 
IpAppAccountManager 



reportNotification (chargingEventlnfo : in TpChargingEventlnfo, assignmentid : in TpAssignmentID) : void 

queryBalanceRes (queryld : in TpAssignmentID, balances : in TpBalanceSet) : void 

queryBalanceErr (queryld : in TpAssignmentID, cause : in TpBalanceQueryError) : void 

retrieveTransactionHistoryRes (retrievallD : in TpAssignmentID, transactionHistory : in 
TpTransactionHistorySet) : void 

retrieveTransactionHistoryErr (retrievallD : in TpAssignmentID, transactionHistoryError : in 
TpTransactionHistoryStatus) : void 

«new» queryBalanceExpiryDateRes (queryld : in TpAssignmentID, dates : in TpBalanceExpiryDateSet) : 
void 

«new» queryBalanceExpiryDateErr (queryld : in TpAssignmentID, cause : in TpBalanceQueryError) : 
void 

«new» updateBalanceRes (requestid : in TpAssignmentID, balance : in TpBalance) : void 

«new» updateBalanceErr (requestid : in TpAssignmentID, cause : in TpBalanceQueryError) : void 

«new» createVoucherRes (requestid : in TpAssignmentID, voucherld : in TpAssignmentID) : void 

«new» createVoucherErr (requestid : in TpAssignmentID, cause : in TpVoucherError) : void 

«new» destroyVoucherRes (requestid : in TpAssignmentID, voucherld : in TpAssignmentID) : void 

«new» destroyVoucherErr (requestid : in TpAssignmentID, voucherld : in TpAssignmentID, cause : in 
TpVoucherError) : void 

«new» queryVoucherRes (queryld : in TpAssignmentID, voucher : in TpVoucher) : void 

«new» queryVoucherErr (queryld : in TpAssignmentID, voucherld : in TpAssignmentID, cause : in 
TpVoucherError) : void 

«new» queryUserVouchersRes (queryld : in TpAssignmentID, vouchers : in TpVoucherSet) : void 

«new» queryUserVouchersErr (queryld : in TpAssignmentID, cause : in TpVoucherError) : void 



8.2.1 Method reportNotification() 

This method is used to notify the appHcation of a charging event. 

Parameters 

chargingEventlnfo : in TpChargingEventlnfo 

Specifies data associated with this charging event. These data include the charging event being notified, the current 
value of the balance after the notified event occurred, and the time at which the charging event occurred. 

assignmentid : in TpAssignmentID 

Specifies the assignment ID that was returned by the createNotification() method. The application can use the 
assignment ID to associate events with event-specific criteria and to act accordingly. 
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8.2.2 Method queryBalanceResQ 



This method indicates that the request to query the balance was successful and it reports the requested balance of an 
account to the application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the balance query request. 

balances : in TpBalanceSet 

Specifies the balance for one or more user accounts. 



8.2.3 Method queryBalanceErrQ 

This method indicates that the request to query the balance failed and it reports the cause of failure to the application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the balance query request. 

cause : in TpBalanceQueryError 

Specifies the error that led to the failure. 

8.2.4 Method retrieveTransactionHistoryRes() 

This method indicates that the request to retrieve the transaction history was successful and it returns the requested 
transaction history. 

Parameters 

retrievallD : in TpAssignmentID 

Specifies the retrievallD of the transaction history retrieval request. 

transactionHistory : in TpTransactionHistorySet 

Specifies the requested transaction history. 

8.2.5 Method retrieveTransactionHistoryErr() 

This method indicates that the request to retrieve the transaction history failed and it reports the cause of failure to the 
application. 

Parameters 

retrievallD : in TpAssignmentID 

Specifies the retrievallD of the transaction history retrieval request. 

transactionHistoryError : in TpTransactionHistoryStatus 

Specifies the error that occurred while retrieving the transaction history. 
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8.2.6 Method «new» queryBalanceExpiryDateResQ 

This method indicates that the request to query the balance expiry date was successful and it reports the requested 
balance expiry date of an account to the application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the balance query expiry date request. 

dates : in TpBalanceExpiryDateSet 

Specifies the balance expiry date for one or more user accounts. 

8.2.7 Method «new» queryBalanceExpiryDateErr() 

This method indicates that the request to query the balance expiry date failed and it reports the cause of failure to the 
application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the balance query expiry date request. 

cause : in TpBalanceQueryError 

Specifies the error that led to the failure. 

8.2.8 Method «new» updateBalanceRes() 

This method indicates that the request to update the balance update was successful and it reports the balance of an 
account to the apphcation. 

Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the balance update request. 

balance : in TpBalance 

Specifies the balance of the account. 

8.2.9 Method «new» updateBalanceErrQ 

This method indicates that the request to update the balance failed and it reports the cause of failure to the application. 

Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the balance update request. 

cause : in TpBalanceQueryError 

Specifies the error that led to the failure. 

8.2.10 Method «new» create VoucherRes() 

This method indicates that the request to create a voucher was successful. 
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Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the voucher create request. 

voucherld : in TpAssignmentID 

Specifies the voucher. 

8.2.1 1 Method «new» create VoucherErr() 

This method indicates that the request to create a voucher failed and it reports the cause of failure to the application. 

Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the voucher create request. 

cause : in TpVoucherError 

Specifies the error that led to the failure. 

8.2.12 Method «new» destroyVoucherRes() 

This method indicates that the request to destroy a voucher was successful. 

Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the request. 

voucherld : in TpAssignmentID 

Specifies the voucher. 

8.2.13 Method «new» destroyVoucherErr() 

This method indicates that the request to destroy a voucher failed and it reports the cause of failure to the application. 

Parameters 

requestid : in TpAssignmentID 

Specifies the ID of the request. 

voucherld : in TpAssignmentID 

Specifies the voucher. 

cause : in TpVoucherError 

Specifies the error that led to the failure. 

8.2.14 Method «new» queryVoucherResQ 

This method indicates that the request to query the voucher information was successful and it reports the amount to the 
application. 
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Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the query voucher amount request. 

voucher : in Tp Voucher 

Specifies the information of the voucher. 

8.2.15 Method «new» queryVoucherErrQ 

This method indicates that the request to query the voucher failed and it reports the cause of failure to the application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the query voucher amount request. 

voucherld : in TpAssignmentID 

Specifies the voucher. 

cause : in TpVoucherError 

Specifies the error that led to the failure. 

8.2.16 Method «new» queryUserVouchersRes() 

This method indicates that the request to query the vouchers was successful and it reports the set of vouchers to the 
application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the query vouchers request. 

vouchers : in TpVoucherSet 

Specifies the set of vouchers for the user. 

8.2.17 Method «new» queryUserVouchersErrQ 

This method indicates that the request to query the vouchers for a user failed and it reports the cause of failure to the 
application. 

Parameters 

queryld : in TpAssignmentID 

Specifies the ID of the query vouchers request. 

cause : in TpVoucherError 

Specifies the error that led to the failure. 
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9 State Transition Diagrams 

9.1 State Transition Diagrams for IpAccountlVlanager 



Creation of IpAccountManager 
by Service Instance Lifecycle 
Manager 



T\ 



enabbleNotifications 
disableNotifications 
query BalanceReq 
retrieveTransactionHistoryReq 



enableNotifications 
disableNotifications 
query BalanceReq 
changeNotification 
getNotification 

retrieveTransactionHistoryReq 
createNotification 

destroyNotification 




IpAccess.terminateServiceAgreernent 



iBAccess.terminateServiceAgreement 



Figure : Application view on the IpAccountlVlanager 

9.1.1 Active state 

In this state a relation between the AppUcation and the Account Management has been established. The state allows the 
application to indicate that it is interested in charging related events, by calling createNotification/enableNotifications. 
In case such an event occurs. Account Manager will inform the application by invoking the operation 
reportNotificationO on the IpAppAccountManager interface. The application can also indicate it is no longer interested 
in certain charging related events by calling destroyNotification/disableNotifications. 

9.1 .2 Notifications created State 

When the Account Manager is in the Notifications created state, events requested with 

createNotification/enableNotifications will be forwarded to the application. In this state the application can request to 
change the notifications or query the Account Manager for the notifications currently set. 



10 Account IVIanagement Service Properties 

The following table lists properties relevant for the Account Management API. 
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Property 


Type 


Description/Interpretation 


P_ EVENT_TYPES 


INTEGER_SET 


Indicates the event types supported by the SCS. Static events 
are the events by which applications are initiated. 


P_ADDRESSPLAN 


INTEGER„SET 


Indicates the supported address plans (defined in 
TpAddressPlan.) E.g. {P_ADDRESS„PLAN_E164, 
P_ADDRESS_PLAN_IP j). Note that more than one address 
plan may be supported. 



The previous table lists properties related to the capabilities of the SCS itself. The following table lists properties that 
are used in the context of the Service Level Agreement, e.g. to restrict the access of applications to the capabilities of 
the SCS. 



Property 


Type 


Description/Interpretation 


P_NOTIFICATION_ADDRESS_RANGES 


XML_ADDRESS_RANGE_SET 


Indicates for which numbers notifications may be set. 
More than one range may be present. For terminating 
notifications they apply to the terminating number, for 
originating notifications they apply only to the 
originating number. 


P_CURRENCY_ALLOWED 


STRING_SET 


Indicates the currencies that can be returned in the 
queryBalanceRes. The valid values for the string set are 
according to ISO-4217. E.g. {'EUR', 'NLG' j. 


P_HISTORY_ALLOWED 


STRING^SET 


Indicates the length of the transaction history interval 
that is allowed to be retrieved by the application. The 
vahd values for the string are according to 
TpDateAndTime. The string-set will be of format 
{"lower_start_time", "upper_stop_time" ) , e.g. {"1998- 
12-04 10:30", "1999-12-04 10:30") 


P_MAX_ADDRESSES_PER_QUERY 


INTEGER_SET 


Indicates the maximum number of addresses which can 
be included in a queryBalanceReq. 



11 



Data Definitions 



11.1 Account IVIanagement Data Definitions 

This clause provides the Account Management specific data definitions necessary to support the OSA interface 
specification. 

The general format of a data definition specification is the following: 

• Data type, that shows the name of the data type. 

• Description, that describes the data type. 

• Tabular specification, that specifies the data types and values of the data type. 

• Example, if relevant, shown to illustrate the data type. 

All data types referenced in this document but not defined in this clause are common data definitions which may be 
found in 3GPP TS 29.198-2. 

11.1.1 IpAppAccountManager 

Defines the address of an IpAppAccountManager Interface. 

11.1.2 IpAppAccountManagerRef 

Defines a Reference to type IpAppAccountManager 
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11.1.3 IpAccountManager 

Defines the address of an IpAccountManager Interface. 

11.1.4 IpAccountManagerRef 

Defines a Reference to type IpAccountManager 

11.1.5 TpBalanceQueryError 

Defines an error that is reported by the Charging service capabiHty feature as a result of a balance query request. 



Name 


Value 


Description 


P_BALANCE_QUERY_OK 





No error occurred while processing the request 


P_BALANCE_QUERY_ERROR_UNDEFINED 


1 


General error, unspecified 


P_BALANCE_QUERY_UNKNOWN_SUBSCRIBER 


2 


Subscriber for which balance is queried is unknown 


P_BALANCE_QUERY_UNAUTHORIZED_APPLICATION 


3 


Apphcation is not authorized to query balance 


P_BALANCE_QUERY_SYSTEM_FAILURE 


4 


System failure. The request could not be handled 



11.1.6 TpChargingEventName 



Defines the charging event for which notifications can be requested by the application. 



Name 


Value 


Description 


P_AM_CHARGING 





End user's account has been charged by an application 


P_AM_RECHARGING 


1 


End user has recharged the account 


P_AM_ACCOUNT_LOW 


2 


Account balance is below the balance threshold 


P_AM_ACCOUNT_ZERO 


3 


Account balance is at zero 


P_AM_ACCOUNT_D I SABLED 


4 


Account has been disabled 



11.1.7 TpBalancelnfo 

Defines the structure of data elements that specifies detailed balance info. 



Structured Member 
Name 


Structured Member 
Type 


Description 


Currency 


TpString 


Currency unit according to ISO-4217 [4]. 


ValuePartA 


Tplnt32 


This data type is identical to a Tplnt32 and specifies the most significant part of the 
composed value. A currency amount is composed as follows: 
( (ValuePartA*2''+ ValuePartB) * 0,0001 ) 


ValuePartB 


Tplnt32 


This data type is identical to a Tplnt32 and specifies the least significant part of the 
composed value. 


Exponent 


Tplnt32 


Specifies the position of the decimal point in the currency amount made up of the 
ValuePartA and the ValuePartB, as described above. 

E.g. an exponent of 4 means a pure integer value, whereas an exponent of 2 means an 
accuracy of 0,01. 


Additional Info 


TpString 


Descriptive string, containing additional information, which is sent to the application 
without prior evaluation. 



As an example, the currency amount composed of a Currency of EUR, a ValuePartA of 0, a ValuePartB of 10 000, and an 
exponent of 2 yields a currency amount of € 100,00. 

Valid Currencies are: 

ADP, AED, AFA, ALL, AMD, ANG, AON, AOR, ARS, ATS, AUD, AWG, AZM, BAM, 
BBD, BDT, BEF, BGL, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, 
BWP, BYB, BZD, CAD, CDF, CHF, CLE, CLP, CNY, COP, CRC, CUP, CVE, GYP, 
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CZK, 


DEM, 


DJF, 


DKK, 


DOP, 


DZD, 


ECS, 


ECV, 


EEK, 


EGP, 


ERN, 


ESP, 


ETB, 


EUR, 


FIM, 


FJD, 


FKP, 


FRF, 


GBP, 


GEL, 


GHC, 


GIP, 


GMD, 


GNF, 


GRD, 


GTQ, 


GWP, 


GYD, 


HKD, 


HNL, 


HRK, 


HTG, 


HUE, 


IDR, 


lEP, 


ILS, 


INR, 


IQD, 


IRR, 


ISK, 


ITL, 


JMD, 


JOD, 


JPY, 


KES, 


KGS, 


KHR, 


KMF, 


KPW, 


KRW, 


KWD, 


KYD, 


KZT, 


LAK, 


LBP, 


LKR, 


LRD, 


LSL, 


LTL, 


LUF, 


LVL, 


LYD, 


MAD, 


MDL, 


MGF, 


MKD, 


MMK, 


MNT, 


MOP, 


MRO, 


MTL, 


MUR, 


MVR, 


MWK, 


MXN, 


MXV, 


MYR, 


MZM, 


NAD, 


NGN, 


NIO, 


NLG, 


NOK, 


NPR, 


NZD, 


OMR, 


PAB, 


PEN, 


PGK, 


PHP, 


PKR, 


PLN, 


PTE, 


PYG, 


QAR, 


ROL, 


RUB, 


RUR, 


RWF, 


SAR, 


SBD, 


SCR, 


SDD, 


SEK, 


SGD, 


SHP, 


SIT, 


SKK, 


SLL, 


SOS, 


SRG, 


STD, 


SVC, 


SYP, 


SZL, 


THB, 


TJR, 


TMM, 


TND, 


TOP, 


TPE, 


TRL, 


TTD, 


TWD, 


TZS, 


UAH, 


UGX, 


USD, 


USN, 


USS, 


UYU, 


UZS, 


VEB, 


VND, 


VUV, 


WST, 


XAF, 


XAG, 


XAU, 


XBA, 


XBB, 


XBC, 


XBD, 


XCD, 


XDR, 


XFO, 


XFU, 


XOF, 


XPD, 


XPF, 


XPT, 


XTS, 


XXX, 


YER, 


YUM, 


ZAL, 


ZAR, 


ZMK, 


ZRN, 


ZWD. 


















XXX 


IS used for transactions where 


no currency is 


involved. 













11.1.8 TpChargingEventlnfo 

Defines the structure of data elements that specifies charging event information. 



Structured Member Name 


Structured Member Type 


Description 


Char gingE vent Name 


TpChar gingE vent Name 


The charging event for which notifications can 
be requested by the apphcation 


Cur rent Balance Info 


TpBalancelnfo 


The current balance of the user"s account 


Char gingE vent Time 


TpTime 


The time at which the charging event occurred. 



11.1.9 TpChargingEventCriteria 

Defines the structure of data elements that specifies charging event criteria. 



Structured Member Name 


Structured Member Type 


Description 


Char gingE vents 


TpChar gingEventNameSet 


Specifies the specific charging 

event criteria used by the 

application to define the event 

required. 


Users 


TpAddressSet 


Specifies the user(s) for which the 

charging events are requested to be 

reported. 



11.1.10 TpChargingEventNameSet 

Defines a collection of TpChargingEventName elements. 

11.1.11 TpChargingEventCriteriaResult 

Defines the Sequence of Data Elements that specify the criteria relating to event requests. 



Sequence Element 
Name 


Sequence Element 
Type 


Char gingEvent Criteria 


TpChargingEventCriteria 


AssignmentID 


TpAssignmentID 
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11.1.12 TpChargingEventCriteriaResultSet 

Defines a collection of TpChargingEventCriteriaResult elements. 



11.1.13 TpBalance 

Defines the structure of data elements that specifies a balance. 



Structured Member Name 


Structured Member Type 


Description 


UserlD 


TpAddress 


Specifies the user to whom the account belongs. 


StatusCode 


TpBalanceQueryError 


Specifies the status code for the balance query request. 


Balanceinf o 


TpBalancelnfo 


Specifies the balance information for the user. 



11.1.14 TpBalanceSet 

Defines a collection of TpBalance elements. 

11.1.15 TpTransactionHistory 

This data type is a sequence of data elements that describes the transaction history. 



Sequence Element 
Name 


Sequence Element 
Type 


Description 


TransactionID 


TpAssignmentID 


Specifies the ID of the specific transaction 


Time St amp 


TpDateAndTime 


Specifies the date and time when the specific transaction was processed. 


Additional Info 


TpString 


Specifies a free format string providing additional information on the specific 
transaction. This could be the applicationDescription provided with the actual 
transaction. 



11.1.16 TpTransactionHistorySet 

Defines a collection of TpTransactionHistory elements. 

11.1.17 TpTransactionHistoryStatus 

Defines a status code that is reported by the Account Manager service capability feature as a result of a transaction 
history retrieval request. 



Name 


Value 


Description 


P_AM_TRANSACTION_ERROR_UNSPECIFIED 





General error, unspecified 


P_AM_TRANSACTION_INVALID_INTERVAL 


1 


An invalid interval for the transaction history was specified. 


P_AM_TRANSACTION_UNKNOWN_ACCOUNT 


2 


No account for the specified user is known. 


P_AM_TRANSACTION_UNAUTHORIZED_APPLICATION 


3 


Application is not authorized to query balance. 


P_AM_TRANSACTION_PROCESSING_ERROR 


4 


A processing error occuiTed while compiling the transaction 
history. 


P_AM_TRANSACTION_SYSTEM_FAILURE 


5 


System failure. The request could not be handled 



11.1.18 TpBalanceExpiryDate 

Defines the structure of data elements that specifies a balance expiry date. 
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Structure Element 
Name 


Structure Element Type 


Structure Element Description 


UserlD 


TpAddress 


Specifies the user to wliom the account belongs. 


StatusCode 


TpBalanceQueryError 


Specifies the status code for the balance query request 


ExpiryDate 


TpDateAndTime 


Defines the expiry date and time 



11.1.19 TpBalanceExpiryDateSet 

Defines a Numbered set of data elements of TpBalanceExpiryDate. 

11.1.20 TpVoucherError 

Defines an error that is reported as a result of a voucher request. 



Name 


Value 


Description 


P_VOUCHER_OK 





No error occurred while processing the request 


P_VOUCHER_UNDEFINED 


1 


General error, unspecified 


P_VOUCHER_UNKNOWN_SUBSCRIBER 


2 


Subscriber is unknown 


P_VOUCHER_UNAUTHORIZED_APPLICATION 


3 


Application is not authorized 


P_VOUCHER_SYSTEM_FAILURE 


4 


System failure. The request could not be handled 



11.1.21 Tp Voucher 

Defines the structure of data elements that specifies a voucher. 



Structure Element 
Name 


Structure Element Type 


Structure Element Description 


VoucherlD 


TpAssignmentID 


Specifies the unique identifier for this voucher. 


UserlD 


TpAddress 


Specifies the user to who the voucher belongs. 


Balanceinf o 


TpBalanceInf o 


Specifies the amount of the voucher. 



11.1.22 TpVoucherSet 

Defines a numbered set of data elements of Tp Voucher. 



12 Exception Classes 



The following are the list of exception classes, which are used in this interface of the API. 



Name 


Description 


P_UNAUTHORIZED_APPLICATION 


Application is not authorized to perform charging operations 



Each exception class contains the following structure: 



Structure Element Name 


Structure Element Type 


Structure Element Description 


Extrainf ormation 


TpString 


Carries extra information to help identify the source of the 
exception, e.g. a parameter name 



£75/ 



3GPP TS 29.1 98-1 1 version 6.4.0 Release 6 38 ETSI TS 1 29 1 98-1 1 V6.4.0 (2005-1 2) 

Annex A (normative): 

OMG IDL Description of Account IVIanagement SCF 

The OMG IDL representation of this interface specification is contained in a text file (am.idl contained in archive 
291981 1V640IDL.ZIP) which accompanies the present document. 
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Annex B (informative): 

W3C WSDL Description of Account IVIanagement SCF 

Significant changes have occurred in Web Services technologies and understanding of how to best apply Web Services 
as a realisation of OS A. These changes are not reflected and therefore this realisation is removed. A future activity may 
provide a replacement for the content of this annex, reflective of current technology and usage expected. 
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Annex C (informative): 

Java™ API Description of the Account IVIanagement SCF 

The JavaT"^ API realisation of this interface specification is produced in accordance with the Java'*^ ReaHsation rules 
defined in Part 1 of this specification series. These rules aim to deliver for Java''^, a developer API, provided as a 
realisation, supporting a Java'^ API that represents the UML specifications. The rules support the production of both 
J2SE'''^ and J2EEr'^ versions of the API from the common UML specifications. 

The J2SE''^ representation of this interface specification is provided as Java'"*^ Code, contained in archive 
291981 1V640J2SE.ZIP that accompanies the present document. 

The J2EE''''^ representation of this interface specification is provided as Java"^ Code, contained in archive 
291981 1V640J2EE.ZIP that accompanies the present document. 



£75/ 



3GPP TS 29.1 98-1 1 version 6.4.0 Release 6 41 ETSI TS 1 29 1 98-1 1 V6.4.0 (2005-1 2) 

Annex D (informative): 

Description of Account IVIanagement for 3GPP2 cdma2000 

networks 

This annex is intended to define the OSA API Stage 3 interface definitions and it provides the complete OSA 
specifications. It is an extension of OSA API specifications capabilities to enable operation in cdma2000 systems 
environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 architecture defined in 

[1] 3GPP2 P.SOOOl-B: "Wireless IP Network Standard", Version 1.0, September 2000; 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 2.0, May 14, 2002; 

[3] 3GPP2 X.S0013: "All-IP Core Network Multimedia Domain", December 2003. 

These requirements are expressed as additions to and/or exclusions from the 3GPP Release 6 specification. The 
information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3GPP 
OSA specifications. 



D.1 General Exceptions 



The term UMTS is not applicable for the cdma2000 family of standards. Nevertheless these terms are used (3GPP TR 
21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions or 
exclusions required. 

CAMEL and CAP mappings are not applicable for cdma2000 systems. 



D.2 Specific Exceptions 
D.2.1 Clause 1: Scope 

There are no additions or exclusions. 

D.2.2 Clause 2: References 

Normative references on 3GPP TS 23.078 and on 3GPP TS 29.078 are not applicable for cdma2000 systems. 

D.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

D.2.4 Clause 4: Account Management SCF 

There are no additions or exclusions. 

D.2. 5 Clause 5: Sequence Diagrams 

There are no additions or exclusions. 
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D.2.6 Clause 6: Class Diagrams 

There are no additions or exclusions. 

D.2.7 Clause 7: The Service Interface Specifications 

There are no additions or exclusions. 

D.2.8 Clause 8: Account Management Interface Classes 

There are no additions or exclusions. 

D.2.9 Clause 9: State Transition Diagrams 

There are no additions or exclusions. 

D.2.10 Clause 10: Account Management Service Properties 

There are no additions or exclusions. 

D.2.1 1 Clause 1 1 : Data Definitions 

There are no additions or exclusions. 

D.2.1 2 Clause 12: Exception Classes 

There are no additions or exclusions. 

D.2.1 3 Annex A (normative): OMG IDL Description of Account 
Management SCF 

There are no additions or exclusions. 

D.2.1 4 Annex B (informative): W3C WSDL Description of Account 
Management SCF 

There are no additions or exclusions. 
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Annex E (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 
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Subject/Comment 


Old 


New 


Mar 2001 


CN 11 


NP-010134 
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- 


CR 29.1 98: for moving TS 29.1 98 from R99 to Pel 4 (N5-01 01 58) 


3.2.0 


1.0.0 


Jun2001 


CN 12 


NP-010327 


- 


- 


Approved at TSG CN#12 and placed under Change Control 


2.0.0 


4.0.0 


Sep 2001 


CN 13 


NP-0 10472 
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- 


Changing references to JAIN 


4.0.0 


4.1.0 


Sep 2001 


CN 13 


NP-0 10472 


002 


- 
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4.0.0 


4.1.0 


Dec 2001 


CN 14 


NP-010602 


003 


- 


Replace Out Parameters with Return Types 


4.1.0 


4.2.0 


Dec 2001 


CN_14 


NP-010602 


004 


— 


Replace erroneous use of incorrect data type TpSessionID by 
TpAssignmentID in Account Management interface 


4.1.0 


4.2.0 


Mar 2002 


CN_15 


NP-020111 


005 


— 


Add P_INVALID_INTERFACE_TYPE exception to 
IpService.setCallbackO and lpService.setCallbackWithSessionlD() 


4.2.0 


4.3.0 


Mar 2002 


CN_15 


NP-020111 


006 


— 


Correction of parameter name in 
IpAccountManager.createNotificationO 


4.2.0 


4.3.0 


Mar 2002 


CN_15 


NP-020111 


007 


- 


Correction of result parameter of getNotification, set in stead of single 
result 


4.2.0 


4.3.0 


Jun 2002 


CN_16 


NP-020193 


008 


- 


Change to new Service Property 

P MAX ADDRESSES PER QUERY for Account Management 


4.3.0 


5.0.0 


Jun 2002 


CN 16 


NP-020182 


009 
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Addition of support for WSDL realisation 


4.3.0 


5.0.0 


Jun 2002 


CN 16 


NP-020183 


010 
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4.3.0 


5.0.0 


Sep 2002 


CN 17 


NP-020436 


Oil 
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5.0.0 
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012 
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Management 
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NP-030025 
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- 


Correction to TpChargingEventCriteria in Account Management 
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5.2.0 


Mar 2003 
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NP-030025 


018 
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Addition of status of methods to Account Management interfaces 


5.1.0 


5.2.0 


Mar 2003 


CN 19 


NP-030035 


019 


- 


Inconsistent description of use of secondary callback 


5.1.0 


5.2.0 


Sep 2003 


CN 21 


NP-030352 


020 


- 


Correction to Java Realisation Annex 


5.2.0 


5.3.0 


Dec 2003 


CN_22 


NP-030556 


021 


— 


Add methods for balanceUpdate(), voucherUpdate() and 
getCreditExpiryDateO to OSA Account Management 


5.3.0 
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Dec 2003 


CN 22 


NP-030553 


022 


- 


Add OSA API support for 3GPP2 networks 


5.3.0 


6.0.0 


Feb 2004 
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- 


Added Java code attachment 291 981 1 J2EE.zip which was delivered 
late by outside developers. See Annex C. 
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Jun 2004 


CN 24 


NP-040271 


024 


- 
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Jun 2004 


CN 24 
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027 
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Correct the P TRIGGERING ADDRESSES service property 
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Jun 2004 
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NP-040273 


028 
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Sep 2004 
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030 
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Correct J2EE source 
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Sep 2004 
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Remove unused Deprecated items 
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Sep 2004 
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032 
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